Release 10.1A: OpenEdge Application Server:
Developing AppServer Applications

Establishing a connection with the CONNECT( ) method

The CONNECT( ) method takes up to four character string arguments in the following order, all of which are optional, depending on the configuration of your AppServer environment:

connection-parameters
userid
password
appserver-info

You use the connection-parameters argument to locate and configure the connection to one or more AppServer instances that support the required business function (application service).

The userid, password, and appserver-info arguments apply only to session-managed configurations and are passed from the client application to the AppServer, which passes them to the Connect procedure (if defined). If a Connect procedure is not defined for the connected AppServer, these arguments are discarded. The requirement to specify these arguments depends entirely on the application service defined for the connected AppServer.

An AppServer can reject a connection request if:

The Connect procedure failed.
There are not enough system resources (for example, AppServer agents) available to service the connection.
The specified session model for the connection is incorrect.

The rest of this section describes these parameters in greater detail.

Connection parameters argument

The connection-parameters argument specifies a comma-separated list of parameters necessary to establish the AppServer connection. These parameters include two types:

A basic set used to connect to an AppServer instance or application service, regardless of the session model.
A set for specifying and managing the session model of the connection.

Table 3–2 describes the basic connection parameters to connect to an AppServer instance or application service, regardless of the session model.

Table 3–2: AppServer basic connection parameters

Connection parameter1	Description
-AppService application-service	If you connect through a NameServer, the name of an application service supported by the specified NameServer. (Defaults to the default service for the specified NameServer.) If you connect directly to an AppServer, this parameter is ignored.
-H [ host_name | IP-address ]	The network address to a NameServer machine or, if you connect directly, to an AppServer machine. You can specify either the TCP/IP host name or the Internet protocol address of the machine. (Defaults to localhost)
-S [ service-name | port-number ]	The UDP port number for a NameServer, or, if you connect directly, the TCP/IP port number for an AppServer connection. You can specify either an explicit port number or a service name. If you use a service name, the method uses the port number associated with that name in the TCP/IP services file. (Defaults to 5162)
-DirectConnect	If specified, the -H and -S parameters are interpreted as the network address and TCP/IP port number of an AppServer connection. Otherwise, the -H and -S parameters are interpreted as the network address and UDP port number of a NameServer.
-ssl	If specified, the connection is direct to the AppServer using Secure Sockets Layer (SSL) tunneling. (Used in conjunction with the -AppService, -H, and -S parameters). Note: Be very sure you need SSL before using this option. SSL incurs more or less heavy performance penalties, depending on resources and load.
-nosessionreuse	If specified, the connection does not reuse the SSL session ID when reconnecting to the same SSL-enabled server (either a Web server with HTTPS or an SSL-enabled AppServer).
-nohostverify	If specified, turns off host verification for an SSL-enabled connection, either using HTTPS with the AIA or using a direct connection to an SSL-enabled AppServer. Without this parameter, the client compares the host name specified for the connection with the Common Name specified in the server digital certificate, and raises an error if they do not match. With this parameter specified, the client never raises the error. For more information on digital certificates, see OpenEdge Getting Started: Core Business Services .
-pf filename	A text file containing any of the other AppServer connection parameters described in this table or Table 3–3. If this file contains any other OpenEdge startup parameters, the method ignores them.
-URL Web-or-AppServer-path	An HTTP (or HTTPS-based) URL to an AIA (for an Internet-secure AppServer connection) or an AppServer-based URL (with or without SSL tunneling for an SSL-enabled AppServer connection). The same URL format is also used to connect Open Clients to an AppServer. For more information see Appendix A "Connecting to AppServers Using a URL." Note: Be very sure you need SSL (either, and especially both, an HTTPS or SSL-enabled AppServer) before using this option. SSL at any point in a networked application incurs more or less heavy performance penalties, depending on resources and load.

1Previous versions of the AppServer allow you to include a network protocol using the -N parameter, which must always specify TCP. While still allowed, it is optional and always defaults to TCP/IP.

Note: Connections to an Internet-secure (HTTPS) or SSL-enabled AppServer require the management of public keys on the client (SSL client) and private keys on the server (SSL server). For an Internet-secure AppServer, the SSL server is the Web server that hosts the AIA. For an SSL-enabled AppServer, the SSL server is the AppServer itself. For information on configuring a Web server for HTTPS, see your Web server documentation. For information on using SSL to secure an AppServer, see the sections on SSL security in Chapter 4, " Design and Implementation Considerations." For information on configuring an AppServer for SSL tunneling, see OpenEdge Application Server: Administration . For more information on SSL and managing private key and digital certificate stores for OpenEdge SSL clients and servers, see OpenEdge Getting Started: Core Business Services .

Table 3–3 describes connection parameters for specifying and managing the session model of the connection.

Table 3–3: AppServer session model connection parameters;

Parameter	Session model/ Default	Description
-sessionModel sessionModel	Session-managed Session-free	Session model supported by the AppServer operating mode, specified by one of the following values: Session-managed Session-free The value is not case sensitive. This parameter is required for session-free application and is optional for session-managed applications. This value must match the AppServer operating mode or the CONNECT( ) method fails. Default: Session-managed
-connectionLifetime nSeconds	Session-free	The maximum number of seconds that a given connection can be reused before it is destroyed. Connections whose lifetime exceeds the specified value are destroyed as they become available. An available connection is one that is not currently reserved to run a request. Bound connections associated with remote persistent procedures are not available for reuse until the persistent procedure is deleted. So, bound connections remain available as long as necessary, even if they exceed the specified value. Default: 300
-initialConnections nConnections	Session-free	The number of connections established when the CONNECT( ) method executes on a given server handle. The value must be greater than zero. If the specified number of connections cannot be created, the CONNECT( ) method fails and any successfully-created connections are closed. Default: 1
-maxConnections nConnections	Session-free	The maximum number of connections that can be created for a given server handle to execute non-persistent external procedures. The value must be greater than or equal to zero. If this value is zero, there is no limit to the number of connections that can be created. Note: For calls to persistent procedures, their internal procedures, and user-defined functions, the client has no limit on the number of connections that can be created. Default: 0
-nsClientMaxPort portNum	Session-manage Session-free	The maximum value for the UDP port number used by the client when communicating with the Name Server. If this value is zero, OpenEdge chooses the NameServer client port randomly. This value should be greater than or equal to the value of the -nsClientMinPort parameter. Default: 0
-nsClientMinPort portNum	Session-manage Session-free	The minimum value for the UDP port number used by the client when communicating with the NameServer. If this value is zero, OpenEdge chooses the NameServer client port randomly. Default: 0
-nsClientPicklistExpiration nSeconds	Session-free	The maximum amount of time, in seconds, that the client retains an AppServer pick list for an application service. Default: 300
-nsClientPicklistSize nPicks	Session-free	The number of AppServer picks to request from the NameServer each time it looks up the available AppServer connections for a given application service name. Default: 1
-nsClientPortRetry nRetries	Session-manage Session-free	The maximum number of attempts that the client makes to get a valid local UDP port number when attempting to communicate with the NameServer. Default: 0
-nsClientDelay nMilliSeconds	Session-manage Session-free	The interval, in milliseconds, that the client waits between attempts to get a valid UDP port number when attempting to communicate with the NameServer. Default: 0

Note that the actual AppServer that the client connects to is controlled by the NameServer based on the application service (-AppService) name specified by the client. The OpenEdge interface in cooperation with the NameServer connects the client application to one of the AppServer instances that supports the specified application service. If you do not specify an application service, the NameServer uses whatever AppServer registers itself as the default service, if any. For more information on load balancing, see the information on load balancing and session models in Chapter 1, " AppServer and Client Interaction."

If the application service is unknown to the NameServer, the client application receives an error. Otherwise, the connection proceeds and any configured Connect procedure executes for the connected AppServer (session-managed only). For more information on application services and NameServers, see the AppServer chapter in OpenEdge Getting Started: Application and Integration Services .

Session-managed application arguments

The userid, password, and appserver-info arguments are optional. However, the requirement to specify these arguments, and to provide specific values for any of them, depends on whether the AppServer Connect procedure is being used on the AppServer you are connecting.

Note: These arguments are ignored for a session-free application service, because AppServer Connect procedures do not execute on a session-free AppServer.

If the AppServer Connect procedure is defined for the AppServer, then you must know how the AppServer Connect procedure is implemented to determine how to specify these values. If you do not specify a value for an argument, the Unknown value (?) is passed to the AppServer Connect procedure for that argument. OpenEdge only passes these values from the CONNECT( ) method to the AppServer Connect procedure. It is the procedure that actually evaluates the values that are passed.

Note: When determining what arguments to pass to the CONNECT( ) method, understand that an AppServer accepts a connection request only if any configured Connect procedure executes successfully.

If the AppServer Connect procedure is not defined for the AppServer, you do not need to pass the three application arguments to the CONNECT( ) method. If you happen to provide them, they are ignored.

For more information on Connect procedures, see Chapter 2, " Programming the AppServer."